home *** CD-ROM | disk | FTP | other *** search
/ The Atari Compendium / The Atari Compendium (Toad Computers) (1994).iso / files / linux.68k / docs / dd-tut~1.z / dd-tut~1
Text File  |  1993-04-12  |  43KB  |  1,136 lines
  1. ************************************************************
  2. *                                                          *
  3. *  Tutorial To Linux Driver Writing -- Character Devices   *
  4. *                                                          *
  5. *                            or,                           *
  6. *                                                          *
  7. *       Now That I'm Wacky, Let Me Do Something (I)        *
  8. *                                                          *
  9. *                 Last Revision: Apr 11, 1993              *
  10. *                                                          *
  11. ************************************************************
  12.  
  13. This document (C) 1993 Robert Baruch.  This document may be freely 
  14. copied as long as the entire title, copyright, this notice, and all of
  15. the introduction are included along with it.  Suggestions, criticisms,
  16. and comments to baruch@nynexst.com.  This document, nor the work
  17. performed by Robert Baruch using Linux, nor the results of said work
  18. are connected in any way to any of the Nynex companies.  This product
  19. 0% organic as defined by California Statute 4Z//7&A.  No artificial
  20. coloring or flavoring.
  21.  
  22. ========================
  23.      Introduction
  24. ========================
  25.  
  26. There is a companion guide to this Tutorial, the Guide to Linux Driver
  27. Writing -- Character Devices This Guide should serve as a reference to 
  28. both beginning and advanced driver writers, and should be used in
  29. conjunction with this Tutorial.
  30.  
  31. -=-=-=-=-=-=-
  32.  
  33. Some words of thanks:
  34.  
  35. Many thanks to:
  36.  
  37.  Donald J. Becker (becker@metropolis.super.org)
  38.  Don "May the Source be With You!" Holzworth (donh@gcx1.ssd.csd.harris.com)
  39.  Michael Johnson (johnsonm@stolaf.edu)
  40.  Karl Heinz Kremer (khk@raster.kodak.com)
  41.  Pat Mackinlay (mackinla@cs.curtin.edu.au)
  42.  ...others too numerous to mention...
  43.  All the driver writers!
  44.  
  45. ...and of course, Linus "That's LIN-uhks" Torvalds and all the guys who helped
  46.  develop Linux into a BLOODY KICKIN' O/S!
  47.  
  48. -=-=-=-=-=-=-
  49.  
  50. ...and now a word of warning:
  51.  
  52. Messing about with drivers is messing with the kernel.  Drivers are run
  53. at the kernel level, and as such are not subject to scheduling.  Further,
  54. drivers have access to various kernel structures.  Before you actually
  55. write a driver, be *damned* sure of what you are doing, lest you end
  56. up having to re-format your harddrive and re-install Linux!
  57.  
  58. The information in this Tutorial is as up-to-date as I could make it.  It also
  59. has no stamp of approval whatsoever by any of the designers of the kernel.
  60. I am not responsible for damage caused to anything as a result of using this
  61. Guide.
  62.  
  63. ========================
  64.   End of Introduction
  65. ========================
  66.  
  67.  
  68. CHAPTRE THE FIRSTE : How did *they* get the device driver in the kernel?
  69. ------------------
  70.  
  71. You have to realize that device drivers really are part of the kernel.  The
  72. kernel can hook in to the functions in your device driver if you tell it
  73. the addresses of some standard functions.  These standard functions are
  74. detailed in the Guide.
  75.  
  76. As a part of the kernel, the code of the device driver must be compiled in
  77. *with* the kernel.  That is, you must alter some Makefiles to compile your
  78. driver and to get it archived into the chr_drv.a library, or you can
  79. archive it yourself and link it in to the kernel at a later compile stage.
  80.  
  81. The first step, before you even write a single line of driver code, is to
  82. make sure you know how to recompile the kernel.  Then go ahead and actually
  83. do it, to be sure you (and your system) are sane.  Of course, you need
  84. the sources to the kernel.  If you have the SLS distribution of Linux, you
  85. already have the sources in /linux.  If you don't have the sources, you
  86. can get it at one of these fine ftp sites near you:
  87.  
  88.   tsx-11.mit.edu:/pub/linux
  89.   sunsite.unc.edu:/pub/Linux
  90.  
  91. Briefly, here's how to compile the kernel (at least this is how it's done
  92. in the SLS release):
  93.  
  94. Go to /linux (or wherever the source for Linux is)
  95. You will see a directory which looks a lot like this:
  96.  
  97. -rw-r--r--  1 baruch      17982 Nov 10 07:54 COPYING
  98. -rw-r--r--  1 baruch       1444 Jan 13 15:24 Configure
  99. -rw-r--r--  1 baruch       6934 Feb 22 13:31 Makefile
  100. -rw-r--r--  1 baruch       4078 Dec 12 06:45 README
  101. drwxrwxr-x  2 baruch        512 Feb 22 13:34 boot
  102. -rw-r--r--  1 baruch       1724 Feb  9 15:07 config.in
  103. drwxrwxr-x  8 baruch        512 Feb 22 13:34 fs
  104. drwxrwxr-x  4 baruch        512 Dec  1 19:40 include
  105. drwxrwxr-x  2 baruch        512 Feb 22 13:34 init
  106. drwxrwxr-x  5 baruch        512 Feb  9 15:11 kernel
  107. drwxrwxr-x  2 baruch        512 Feb  9 15:11 lib
  108. -rwxr-xr-x  1 baruch        166 Nov 10 07:54 makever.sh
  109. drwxrwxr-x  2 baruch        512 Feb 22 13:34 mm
  110. drwxrwxr-x  3 baruch        512 Feb  9 15:11 net
  111. drwxrwxr-x  2 baruch        512 Feb 22 13:34 tools
  112. drwxrwxr-x  2 baruch        512 Feb 22 13:34 zBoot
  113.  
  114. The README file should contain instructions, but here's how anyway:
  115.  
  116. Log in as root.
  117.  
  118. make clean   (Do this only once.  Otherwise you'll have to sit around
  119.               for 45 minutes or so while the whole thing recompiles)
  120. make config  (Answer the questions -- usually needed only the first time)
  121. make dep     (Makes dependencies)
  122. make         (makes the kernel)
  123.  
  124. You should end up with an Image file.  This is the kernel.  Put it where
  125. you like (LILO users should take it from there).  To make a bootable disk,
  126. just pop a DOS formatted disk in drive A, and do:
  127.  
  128. make disk
  129.  
  130. ------------------------------------------------------------------------
  131.  
  132. CHAPTER TWO: The simplest driver you've ever seen.
  133. ------------
  134.  
  135. Now, the directory you're interested in is <src>/kernel/chr_drv.  This is
  136. where all the character device drivers are kept.  Go to that directory.
  137. Open up a new file, and call it testdata.c.  Here is what you should
  138. put in it:
  139.  
  140. ========================================
  141.       File Listing 1: testdata.c
  142. ========================================
  143.  
  144. #include <linux/kernel.h>
  145. #include <linux/sched.h>
  146. #include <linux/tty.h>
  147. #include <linux/signal.h>
  148. #include <linux/errno.h>
  149.  
  150. #include <asm/io.h>
  151. #include <asm/segment.h>
  152. #include <asm/system.h>
  153. #include <asm/irq.h>
  154.  
  155. unsigned long test_init(unsigned long kmem_start)
  156. {
  157.   printk("Test Data Generator installed.\n");
  158.   return kmem_start;
  159. }
  160.  
  161. ========================================
  162.  
  163. The include files are all there for convenience.  You may need them later.
  164. All this driver does is upon initialization, display a message.
  165.  
  166. Now, to get this driver into the kernel, you need to do several things.
  167. The first two things do in the chr_drv directory:
  168.  
  169. I.  Get the kernel to call your init function on bootup.  To do this,
  170.     edit the mem.c file, and go to the very end to the function
  171.     chr_drv_init.  It looks something like this:
  172.  
  173.   long chr_dev_init(long mem_start, long mem_end)
  174.   {
  175.         if (register_chrdev(1,"mem",&memory_fops))
  176.                 printk("unable to get major 1 for memory devs\n");
  177.         mem_start = tty_init(mem_start);
  178.         mem_start = lp_init(mem_start);
  179.         mem_start = mouse_init(mem_start);
  180.         mem_start = soundcard_init(mem_start);
  181.         return mem_start;
  182.   }
  183.  
  184.     You need to add your test_init function to the code.  Put it right
  185.     before the return:
  186.  
  187.   mem_start = test_init(mem_start);
  188.  
  189.     Save the file.
  190.  
  191. II.  Edit the Makefile to compile testdata.c.  Edit the Makefile, and add
  192.      testdata.o to the OBJS list.  This will cause the make utility to
  193.      compile testdata.c into an object file, and then add it to the
  194.      chr_drv.a library archive.
  195.  
  196.      Save the file.
  197.  
  198. The next step is to re-compile the kernel.  Go to the <src> directory,
  199. and do a make from the top as described in the first chapter.  There is
  200. no point in doing a "make clean" or "make config".  If all goes well, the 
  201. make should proceed down to chr_drv, and compile your testdata.c file.  
  202. If there are warnings or errors, do a ctrl-C to break out of the make, 
  203. and fix the problem.
  204.  
  205. Once you are left with an Image file, put the Image file where LILO
  206. wants it, or use "make disk" to make a bootable disk.  It's a good
  207. idea to save your old Image file (or save the disk it was on).
  208.  
  209. Now reboot.  When Linux comes up again, you should see your message
  210. printed on bootup after all the char